

<!DOCTYPE html>


<html lang="en" data-content_root="./" >

  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Best practices &#8212; nvtx</title>
  
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
  </script>
  <!--
    this give us a css class that will be invisible only if js is disabled
  -->
  <noscript>
    <style>
      .pst-js-only { display: none !important; }

    </style>
  </noscript>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="_static/styles/theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />

    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
    <link rel="stylesheet" type="text/css" href="_static/styles/nvidia-sphinx-theme.css?v=df3ac72c" />
  
  <!-- So that users can add custom icons -->
  <script src="_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script>
  <!-- Pre-loaded scripts that we'll load fully later -->
  <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />

    <script src="_static/documentation_options.js?v=29c81e07"></script>
    <script src="_static/doctools.js?v=9bcbadda"></script>
    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script>DOCUMENTATION_OPTIONS.pagename = 'best_practices';</script>
    <link rel="icon" href="_static/favicon.png"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Automatic function annotation" href="automatic_annotations.html" />
    <link rel="prev" title="Annotation Attributes" href="annotation_attributes.html" />

  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
  <meta name="docsearch:version" content="" />


  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

  
  
  <div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
  
  <div id="pst-scroll-pixel-helper"></div>
  
  <button type="button" class="btn rounded-pill" id="pst-back-to-top">
    <i class="fa-solid fa-arrow-up"></i>Back to top</button>

  
  <dialog id="pst-search-dialog">
    
<form class="bd-search d-flex align-items-center"
      action="search.html"
      method="get">
  <i class="fa-solid fa-magnifying-glass"></i>
  <input type="search"
         class="form-control"
         name="q"
         placeholder="Search the docs ..."
         aria-label="Search the docs ..."
         autocomplete="off"
         autocorrect="off"
         autocapitalize="off"
         spellcheck="false"/>
  <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form>
  </dialog>

  <div class="pst-async-banner-revealer d-none">
  <aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>

  
    <header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
  <button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation">
    <span class="fa-solid fa-bars"></span>
  </button>
  
  
  <div class="col-lg-3 navbar-header-items__start">
    
      <div class="navbar-item">

  
    
  

<a class="navbar-brand logo" href="index.html">
  
  
  
  
  
    
    
      
    
    
    <img src="_static/nvidia-logo-horiz-rgb-blk-for-screen.svg" class="logo__image only-light" alt="nvtx - Home"/>
    <img src="_static/nvidia-logo-horiz-rgb-wht-for-screen.svg" class="logo__image only-dark pst-js-only" alt="nvtx - Home"/>
  
  
    <p class="title logo__title">nvtx</p>
  
</a></div>
    
  </div>
  
  <div class="col-lg-9 navbar-header-items">
    
    
    <div class="navbar-header-items__end">
      
        <div class="navbar-item navbar-persistent--container">
          

<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
 <i class="fa-solid fa-magnifying-glass"></i>
 <span class="search-button__default-text">Search</span>
 <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
        </div>
      
      
        <div class="navbar-item">

<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode"  data-bs-placement="bottom" data-bs-toggle="tooltip">
  <i class="theme-switch fa-solid fa-sun                fa-lg" data-mode="light" title="Light"></i>
  <i class="theme-switch fa-solid fa-moon               fa-lg" data-mode="dark"  title="Dark"></i>
  <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"  title="System Settings"></i>
</button></div>
      
    </div>
    
  </div>
  
  
    <div class="navbar-persistent--mobile">

<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
 <i class="fa-solid fa-magnifying-glass"></i>
 <span class="search-button__default-text">Search</span>
 <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
    </div>
  

  
    <button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page">
      <span class="fa-solid fa-outdent"></span>
    </button>
  
</div>

    </header>
  

  <div class="bd-container">
    <div class="bd-container__inner bd-page-width">
      
      
      
      <dialog id="pst-primary-sidebar-modal"></dialog>
      <div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar">
        



  
    
  

<a class="navbar-brand logo" href="index.html">
  
  
  
  
  
    
    
      
    
    
    <img src="_static/nvidia-logo-horiz-rgb-blk-for-screen.svg" class="logo__image only-light" alt="nvtx - Home"/>
    <img src="_static/nvidia-logo-horiz-rgb-wht-for-screen.svg" class="logo__image only-dark pst-js-only" alt="nvtx - Home"/>
  
  
    <p class="title logo__title">nvtx</p>
  
</a>


  
  <div class="sidebar-header-items sidebar-primary__section">
    
    
    
    
      <div class="sidebar-header-items__end">
        
          <div class="navbar-item">

<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode"  data-bs-placement="bottom" data-bs-toggle="tooltip">
  <i class="theme-switch fa-solid fa-sun                fa-lg" data-mode="light" title="Light"></i>
  <i class="theme-switch fa-solid fa-moon               fa-lg" data-mode="dark"  title="Dark"></i>
  <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto"  title="System Settings"></i>
</button></div>
        
      </div>
    
  </div>
  
    <div class="sidebar-primary-items__start sidebar-primary__section">
        <div class="sidebar-primary-item">



<nav class="bd-docs-nav bd-links"
     aria-label="Table of Contents">
  <p class="bd-links__title" role="heading" aria-level="1">Table of Contents</p>
  <div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav">
<li class="toctree-l1 current active has-children"><a class="reference internal" href="overview.html">Overview</a><details open="open"><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="annotate.html">Function Decorator and Context Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="annotation_types.html">Annotation Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="annotation_attributes.html">Annotation Attributes</a></li>
<li class="toctree-l2 current active"><a class="current reference internal" href="#">Best practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="automatic_annotations.html">Automatic function annotation</a></li>
</ul>
</details></li>
</ul>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
</ul>
<p aria-level="2" class="caption" role="heading"><span class="caption-text">Project Links</span></p>
<ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference external" href="https://github.com/NVIDIA/NVTX/">GitHub</a></li>
<li class="toctree-l1"><a class="reference external" href="https://pypi.org/project/nvtx/">PyPI</a></li>
<li class="toctree-l1"><a class="reference external" href="https://nvidia.github.io/NVTX/doxygen/">C Docs</a></li>
<li class="toctree-l1"><a class="reference external" href="https://nvidia.github.io/NVTX/doxygen-cpp/">C++ Docs</a></li>
</ul>
</div>
</nav></div>
    </div>
  
  
  <div class="sidebar-primary-items__end sidebar-primary__section">
  </div>



      </div>
      
      <main id="main-content" class="bd-main" role="main">
        
        
          <div class="bd-content">
            <div class="bd-article-container">
              
              <div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
  
    <div class="header-article-items__start">
      
        <div class="header-article-item">

<nav aria-label="Breadcrumb" class="d-print-none">
  <ul class="bd-breadcrumbs">
    
    <li class="breadcrumb-item breadcrumb-home">
      <a href="index.html" class="nav-link" aria-label="Home">
        <i class="fa-solid fa-home"></i>
      </a>
    </li>
    
    <li class="breadcrumb-item"><a href="overview.html" class="nav-link">Overview</a></li>
    
    <li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">Best practices</span></li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section id="best-practices">
<h1>Best practices<a class="headerlink" href="#best-practices" title="Link to this heading">#</a></h1>
<section id="give-don-t-take">
<h2>Give, don’t take<a class="headerlink" href="#give-don-t-take" title="Link to this heading">#</a></h2>
<p>NVTX is primarily a one-way API. Your program gives information to the tool,
but it does not get actionable information back from the tool.
Some NVTX functions return values, but these should only be used as inputs to other NVTX functions.
Programs should behave exactly the same regardless of whether a tool is present or not.</p>
</section>
<section id="isolate-nvtx-annotations-in-a-library-using-a-domain">
<h2>Isolate NVTX annotations in a library using a domain<a class="headerlink" href="#isolate-nvtx-annotations-in-a-library-using-a-domain" title="Link to this heading">#</a></h2>
<p>Programs may use multiple libraries that produce NVTX annotations.
A library should isolate its annotations by creating them within a dedicated domain.
Tools can group annotation data by library,
and provide options for which domains to enable or disable during the program execution.</p>
</section>
<section id="use-categories-to-organize-annotations">
<h2>Use categories to organize annotations<a class="headerlink" href="#use-categories-to-organize-annotations" title="Link to this heading">#</a></h2>
<p>While domains are intended to separate the annotations from different libraries,
it may be useful to have separate categories for annotations within a library.
Tools are encouraged to logically group annotations into categories.
Using slashes in category names like filesystem paths allows the user to
create a hierarchy of categories, and tools should handle these as a hierarchy.</p>
</section>
<section id="reduce-cache-lookups">
<h2>Reduce cache lookups<a class="headerlink" href="#reduce-cache-lookups" title="Link to this heading">#</a></h2>
<p>NVTX is designed to produce minimal overhead during the program execution.
As such, it caches <a class="reference internal" href="reference.html#nvtx.Domain" title="nvtx.Domain"><code class="xref py py-class docutils literal notranslate"><span class="pre">nvtx.Domain</span></code></a> and <a class="reference internal" href="reference.html#nvtx._lib.lib.EventAttributes" title="nvtx._lib.lib.EventAttributes"><code class="xref py py-class docutils literal notranslate"><span class="pre">nvtx._lib.lib.EventAttributes</span></code></a> objects,
as well as <a class="reference internal" href="reference.html#nvtx._lib.lib.RegisteredString" title="nvtx._lib.lib.RegisteredString"><code class="xref py py-class docutils literal notranslate"><span class="pre">nvtx._lib.lib.RegisteredString</span></code></a> objects and category IDs.</p>
<p>The functions <a class="reference internal" href="reference.html#nvtx.mark" title="nvtx.mark"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.mark()</span></code></a>, <a class="reference internal" href="reference.html#nvtx.push_range" title="nvtx.push_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.push_range()</span></code></a>, <a class="reference internal" href="reference.html#nvtx.pop_range" title="nvtx.pop_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.pop_range()</span></code></a>,
<a class="reference internal" href="reference.html#nvtx.start_range" title="nvtx.start_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.start_range()</span></code></a>, and <a class="reference internal" href="reference.html#nvtx.end_range" title="nvtx.end_range"><code class="xref py py-func docutils literal notranslate"><span class="pre">nvtx.end_range()</span></code></a> are convenient to use,
but they include cache lookups for the domain and event attributes.
Therefore, for best performance, it’s better to use the methods from <a class="reference internal" href="reference.html#nvtx.Domain" title="nvtx.Domain"><code class="xref py py-class docutils literal notranslate"><span class="pre">nvtx.Domain</span></code></a> instead.
For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">nvtx</span>

 <span class="k">def</span> <span class="nf">my_func</span><span class="p">(</span><span class="n">param</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>
     <span class="c1"># This call includes a cache lookup for the domain, the message registered string,</span>
     <span class="c1"># the category ID and the event attributes object.</span>
     <span class="c1"># See `my_func_fast` for a faster alternative.</span>
     <span class="n">nvtx</span><span class="o">.</span><span class="n">mark</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s1">&#39;my_func&#39;</span><span class="p">,</span> <span class="n">domain</span><span class="o">=</span><span class="s1">&#39;My Lib&#39;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s1">&#39;my_category&#39;</span><span class="p">,</span> <span class="n">payload</span><span class="o">=</span><span class="n">param</span><span class="p">)</span>

     <span class="c1"># continue with the function logic</span>

<span class="c1"># Save a reference to the domain object,</span>
<span class="c1"># so it can be accessed everywhere in the library code,</span>
<span class="c1"># to avoid multiple calls to nvtx.get_domain()</span>
<span class="n">domain</span> <span class="o">=</span> <span class="n">nvtx</span><span class="o">.</span><span class="n">get_domain</span><span class="p">(</span><span class="s1">&#39;My Lib&#39;</span><span class="p">)</span>

<span class="c1"># Reuse category IDs and EventAttributes objects when possible</span>
<span class="c1"># to avoid multiple calls to nvtx.get_category_id() and nvtx.get_event_attributes()</span>
<span class="n">category_id</span> <span class="o">=</span> <span class="n">domain</span><span class="o">.</span><span class="n">get_category_id</span><span class="p">(</span><span class="s1">&#39;my_category&#39;</span><span class="p">)</span>
<span class="n">attr</span> <span class="o">=</span> <span class="n">domain</span><span class="o">.</span><span class="n">get_event_attributes</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s1">&#39;my_func&#39;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">my_func_fast</span><span class="p">(</span><span class="n">param</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;Faster version of my_func() using the domain object directly.&quot;&quot;&quot;</span>
    <span class="n">attr</span><span class="o">.</span><span class="n">payload</span> <span class="o">=</span> <span class="n">param</span>
    <span class="n">domain</span><span class="o">.</span><span class="n">mark</span><span class="p">(</span><span class="n">attr</span><span class="p">)</span>    <span class="c1"># No cache lookups</span>

    <span class="c1"># continue with the function logic</span>
</pre></div>
</div>
</section>
</section>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer d-print-none">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="annotation_attributes.html"
       title="previous page">
      <i class="fa-solid fa-angle-left"></i>
      <div class="prev-next-info">
        <p class="prev-next-subtitle">previous</p>
        <p class="prev-next-title">Annotation Attributes</p>
      </div>
    </a>
    <a class="right-next"
       href="automatic_annotations.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">Automatic function annotation</p>
      </div>
      <i class="fa-solid fa-angle-right"></i>
    </a>
</div>
                </footer>
              
            </div>
            
            


              
                <dialog id="pst-secondary-sidebar-modal"></dialog>
                <div id="pst-secondary-sidebar" class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item">
<div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> On this page
  </div>
  <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#give-don-t-take">Give, don’t take</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#isolate-nvtx-annotations-in-a-library-using-a-domain">Isolate NVTX annotations in a library using a domain</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#use-categories-to-organize-annotations">Use categories to organize annotations</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#reduce-cache-lookups">Reduce cache lookups</a></li>
</ul>
  </nav></div>

</div></div>
              
            

          </div>
          <footer class="bd-footer-content">
            
          </footer>
        
      </main>
    </div>
  </div>
  
  <!-- Scripts loaded after <body> so the DOM is not blocked -->
  <script defer src="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf"></script>
<script defer src="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf"></script>

  <footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
  
    <div class="footer-items__start">
      
        <div class="footer-item">
<a class="footer-brand logo" href="https://www.nvidia.com">
  <img src="_static/nvidia-logo-horiz-rgb-1c-blk-for-screen.svg" class="logo__image only-light" alt="NVIDIA"/>
  <img src="_static/nvidia-logo-horiz-rgb-1c-wht-for-screen.svg" class="logo__image only-dark" alt="NVIDIA"/>
</a></div>
      
        <div class="footer-item">

<div class="footer-links">
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/privacy-policy/">Privacy Policy</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/privacy-center/">Manage My Privacy</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/preferences/start/">Do Not Sell or Share My Data</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/terms-of-service/">Terms of Service</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/accessibility/">Accessibility</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/about-nvidia/company-policies/">Corporate Policies</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/product-security/">Product Security</a>
   | 
  
  
  
  <a class="external" href="https://www.nvidia.com/en-us/contact/">Contact</a>
  
  
  
</div>
</div>
      
        <div class="footer-item">




  <p class="copyright">
    
      Copyright © 2020-2025, NVIDIA Corporation.
      <br/>
    
  </p>
</div>
      
    </div>
  
  
  
</div>

  </footer>
  </body>
</html>